How to use the ImsEncPci control in Visual C:
=============================================

The following sequence instructs how to build an application
using the ImsEncPci control. The sample application demonstrates
a basic connection with the card(s) by letting flash ten times
the two LEDs of all detected cards upon pressing a button.

 1. Create a new Visual C project ('File', 'New', 'Projects',
    'MFC AppWizard(exe)'), specify the 'Project name' and press
    'OK'.

 2. In step 1 of the AppWizard select 'Dialog based'.
    Other selections of the AppWizard are OK (press 'Finish').

 3. Select 'Project', 'Add To Project', 'Components and Controls'.
    The 'Components and Controls Gallery' appears.
 4. Double-click the 'Registered ActiveX Controls' entry.
    The available ActiveX controls are displayed.
 5. Select the 'ImsEncPci Control', and click the 'Insert' button.
    Answer OK to 'Insert this component?'.
    Answer OK in the 'Confirm Classes' box.
 6. Close the 'Components and Controls Gallery'.
 7. Enter the dialog (double-click the second item under
    ResourceView, Dialog).
 8. If the dialog editor's toolbox (titled 'Controls') is not
    visible, right-click the mouse on a free space in the dialog
    and check the 'Controls' entry.
    In the dialog editor's toolbox there should be a new control,
    labeled EncPci (possibly only part of the 'EncPci' text is
    visible, it's OK). Create in the dialog a new object of the
    'EncPci' control. This object will be invisible at run time.
 9. Enter the Classwizard (View, ClassWizard).
10. Select the 'Member Variables' tab.
11. Double-click on 'IDC_IMSENCPCICTRL1', and specify the 'Member
    variable name', as, say, 'm_ImsEncPci'. Click OK, OK.
    The control is now available.
12. In order to make control's symbolic constants (such as LedRed)
    recognizable to your code:
    * Copy the 'EncPciConst.h' file from this folder to your new
      Visual C project folder.
    * Add this file to the project ('Project', 'Add To Project',
      'Files', select 'EncPciConst.h', 'OK').
    * In dialog's header file (...Dlg.h) there's an
      '#include "imsencpci.h"' statement that was added by the
      Classwizard.
      Follow this line with an '#include "EncPciConst.h"' statement.
13. In dialog's source file ...Dlg.cpp:
    * In the beginning, after the #include lines (before the
      CAboutDlg dialog) add the following lines:
        #define MAX_PCI_CARDS 10
        // (MAX_PCI_CARDS is rather arbitrary. The array below has MAX_PCI
        // elements, indexed 0 through MAX_PCI_CARDS-1.)
        long CardHandleArray[MAX_PCI_CARDS-1] ;
        short CardsDetected ;

    * In the OnInitDialog routine, after the line -
	// TODO: Add extra initialization here
    - add the following code:
                char msg [200] ;
                long CardHandle ;
		short CardIndex ;
		short OK ;  // 0 = Success, 1 = Failure.
		m_ImsEncPci.SetActive(1); // Make the control active.
                    // During run-time, this function makes the control
                    // active, i.e., all its functions become available.
        // Locate all the existing EIC-325/PCI cards:
		for (CardIndex = 0 ; (CardIndex < MAX_PCI_CARDS) ; CardIndex++) {
			OK = m_ImsEncPci.GetCardHandle (&CardHandle, CardIndex) ;
			if (OK == 0) break ;  // No more cards.

            // (EIC-325/PCI card detected.)

            // Store the result in an array:
            CardHandleArray[CardIndex] = CardHandle ;
		}

        // Report how many cards were detected:
        // Note that current CardIndex = how many cards were detected.
        CardsDetected = CardIndex ;
        switch (CardsDetected) 
        {
            case 0:
				MessageBox("No 'EIC-325/PCI' cards detected!", NULL, MB_ICONSTOP) ;
				exit(0) ;
                break ;
            case 1:
				MessageBox("One 'EIC-325/PCI' card detected.") ;
				break ;
            default:
                sprintf (msg, "%d 'EIC-325/PCI' cards were detected. The 'Flash' will apply sequentially to all recognized cards.", CardsDetected) ;
				MessageBox(msg) ;
                break ;
        }
14. To try the control:
    * Add a new button.
    * Edit its OnButton routine by the following sequence:
      * Double-click the new button
      * Double-click 'BN_CLICKED'
      * Click 'OK'
      * Click 'Edit Existing'
    * Add to the OnButton routine the following code:
	// Flash the LEDs of all detected card(s):
        for (short CardIndex = 0 ; CardIndex < CardsDetected ; CardIndex++) {
        	long CardHandle = CardHandleArray[CardIndex] ;
        	for (int i=1 ; i<=10 ; i++ ) {
        		m_ImsEncPci.SetLed(CardHandle,LedYellow,TurnOff);
        		m_ImsEncPci.SetLed(CardHandle,LedRed,TurnOn);
        		Sleep(100);
        		m_ImsEncPci.SetLed(CardHandle,LedYellow,TurnOn);
        		m_ImsEncPci.SetLed(CardHandle,LedRed,TurnOff);
        		Sleep(100);
        	}
        }
    * Make some 'cosmetics' such as removing unnecessary elements
      in the dialog ('TODO' and 'Cancel'), etc.

15. The code of the sample application is ready. Build the
    executable and run it. Pressing the new button should flash
    ten times the two LEDs of all detected cards, indicating that
    your application communicates well with the card via the
    control.


Note
----
The folder EncPciBasicTest includes a sample basic project that
was created according to the instructions above. The output files
generated by Visual C builder are directed to the folder Debug,
but are not supplied, as these are big files and may be reproduced
easily by the user running 'Rebuild All'. Though, the main output
file (EncPciBasicTest.exe) is supplied in the 'EncPciBasicTest'
folder. It was not put in the Debug folder in order to avoid
conflict when the user runs 'Rebuild All'.